home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / NameRegistry.a < prev    next >
Encoding:
Text File  |  1996-05-01  |  32.0 KB  |  1,032 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        NameRegistry.a
  3. ;
  4. ;    Contains:    NameRegistry Interfaces
  5. ;
  6. ;    Version:    Technology:    System 8
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__NAMEREGISTRY__') = 'UNDEFINED' THEN
  19. __NAMEREGISTRY__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE THEN
  25. ;
  26. ; These definitions apply to both the System7 and System8 interfaces
  27. ; RegEntryRef:    The Global Entry Reference
  28. ;
  29. RegEntryRef                RECORD 0
  30. contents                 ds.l    4                ; offset: $0 (0)
  31. sizeof                     EQU *                    ; size:   $10 (16)
  32.                         ENDR
  33.  
  34. kRegPathNameSeparator            EQU        58                    ; 0x3A 
  35.  
  36. kRegMaxPropertyNameLength        EQU        31                    ; Max length of Property Name (terminator not included) 
  37. RegPropertyNameBuf        RECORD 0
  38. elements                 ds.b    32
  39. sizeof                     EQU *                    ; size:   $20 (32)
  40.                         ENDR
  41.  
  42.  
  43.     ENDIF
  44.     IF FOR_SYSTEM8_PREEMPTIVE THEN
  45. ;
  46. ;------------------------------------------------------------------------------------
  47. ;Name Registry Interface for System 8
  48. ;------------------------------------------------------------------------------------
  49. ;
  50. ;
  51. ;------------------------------------------------------------------------------------
  52. ; Foundation Types
  53. ;------------------------------------------------------------------------------------
  54. ;
  55. ;  Entry Name Definitions (Entry Names are C-Strings)
  56.  
  57. kRegMaxEntryNameLength            EQU        47                    ; Max length of a C-String Entry Name (terminator not included) 
  58. ;  length of RegEntryNameBuf = kRegMaxEntryNameLength +1
  59. RegEntryNameBuf            RECORD 0
  60. elements                 ds.b    48
  61. sizeof                     EQU *                    ; size:   $30 (48)
  62.                         ENDR
  63.  
  64.  
  65. ;  Create Entry Options
  66. ; typedef OptionBits                     RegCreateEntryOptions
  67.  
  68. ;  use "kNilOptions" for no options
  69.  
  70. kRegCreateResidentEntry            EQU        $00000001            ; make entry resident 
  71. ;  Delete Entry Options
  72. ; typedef OptionBits                     RegDeleteEntryOptions
  73.  
  74. ;  use "kNilOptions" for no options
  75.  
  76. kRegDeleteEmbeddedEntries        EQU        $00000001            ; delete embedded entries 
  77. ;  Entry Iterator
  78.  
  79.  
  80. ;  Entry Iterator Options
  81. ; typedef OptionBits                     RegEntryIteratorOptions
  82.  
  83. ;  use "kNilOptions" for no options
  84.  
  85. kRegIterateEmbeddedEntries        EQU        $00000002            ; iterate embedded entries 
  86. ;
  87. ; Property Instances
  88. ; An instance value for a property is assigned by the Name Registry when the
  89. ; instance is created.  This value is used to distinguish this instance from any
  90. ; other instances of the property.  Instance values are unique and persistent for
  91. ; the life of the property. Thus, clients can obtain a reference to a property (name
  92. ; and instance value) and use that reference until the property is deleted or the
  93. ; system is restarted.  At restart, new instance values are assigned to all
  94. ; properties, including any restored persistent properties.
  95. ;
  96. ; typedef UInt32                         RegPropertyInstance
  97.  
  98.  
  99. kRegNilPropertyInstance            EQU        $00000000            ; nil property instance 
  100. kRegAnyPropertyInstance            EQU        $FFFFFFFF            ; any property instance 
  101. kRegAllPropertyInstances        EQU        $FFFFFFFE            ; all property instances 
  102. ;  Create Property Options
  103. ; typedef OptionBits                     RegCreatePropertyOptions
  104.  
  105. ;  use "kNilOptions" for no options
  106.  
  107. kRegMultiInstanceProperty        EQU        $00000001            ; multiple-instance property 
  108. ;  Property Iterator
  109.  
  110.  
  111. ;  Transaction Reference
  112.  
  113.  
  114. ;  Nil Transaction Reference
  115.  
  116. kRegNilTransaction                EQU        0
  117. ;
  118. ;------------------------------------------------------------------------------------
  119. ; Name Registry Calls
  120. ;------------------------------------------------------------------------------------
  121. ;
  122. ;
  123. ;------------------------------------------------------------------------------------
  124. ; EntryRef Handling
  125. ;------------------------------------------------------------------------------------
  126. ;
  127. ;  Compare two EntryRef's for equality. 
  128. ;
  129. ; extern Boolean RegEntryRefIsEqual(const RegEntryRef *ref1, const RegEntryRef *ref2)
  130. ;
  131.     IF GENERATINGCFM THEN
  132.         IMPORT_CFM_FUNCTION RegEntryRefIsEqual
  133.     ENDIF
  134.  
  135. ;
  136. ;------------------------------------------------------------------------------------
  137. ; Adding and Deleting Entries
  138. ;------------------------------------------------------------------------------------
  139. ;
  140. ;
  141. ; Create an Entry
  142. ; If (parentEntry) is NULL, the path name is assumed to be an absolute path name
  143. ; rooted to the anonymous, unnamed root.  
  144. ; Note, RegCreateEntry only creates a single entry, the one at the end of the path.
  145. ; Thus, all parent entries along the path to the new entry (ancestors) must already
  146. ; exist.
  147. ;
  148. ;
  149. ; extern OSStatus RegCreateEntry(RegTransaction transaction, const RegEntryRef *parentEntry, const char *pathName, RegCreateEntryOptions options, RegEntryRef *newEntry)
  150. ;
  151.     IF GENERATINGCFM THEN
  152.         IMPORT_CFM_FUNCTION RegCreateEntry
  153.     ENDIF
  154.  
  155. ;
  156. ; Delete an Entry or Subtree
  157. ; RegDeleteEntry can be used to delete a single entry or a complete subtree.
  158. ; To delete a subtree, set the RegDeleteEmbedded option.
  159. ; All properties for deleted entries are also deleted.
  160. ;
  161. ;
  162. ; extern OSStatus RegDeleteEntry(RegTransaction transaction, const RegEntryRef *ref, RegDeleteEntryOptions options)
  163. ;
  164.     IF GENERATINGCFM THEN
  165.         IMPORT_CFM_FUNCTION RegDeleteEntry
  166.     ENDIF
  167.  
  168. ;
  169. ;------------------------------------------------------------------------------------
  170. ; LookUp Entry by Name
  171. ;------------------------------------------------------------------------------------
  172. ;
  173. ;
  174. ; Lookup Entry
  175. ; Locates an entry given a specified subroot (searchPointRef) and path name.  If the
  176. ; searchPointRef pointer is NULL, the path name is assumed to be an absolute path
  177. ; name rooted to the root of the Registry.
  178. ;
  179. ;
  180. ; extern OSStatus RegLookupEntry(RegTransaction transaction, const RegEntryRef *searchPointRef, const char *pathName, RegEntryRef *foundEntry)
  181. ;
  182.     IF GENERATINGCFM THEN
  183.         IMPORT_CFM_FUNCTION RegLookupEntry
  184.     ENDIF
  185.  
  186. ;
  187. ;------------------------------------------------------------------------------------
  188. ;Get Entry Name and Parent
  189. ;------------------------------------------------------------------------------------
  190. ;
  191. ;
  192. ; Retrieve the name component for the specified entry, and return the EntryRef for
  193. ; the parent entry.
  194. ;
  195. ;
  196. ; extern OSStatus RegGetEntryName(RegTransaction transaction, const RegEntryRef *entryRef, RegEntryRef *parentEntry, char *nameComponent)
  197. ;
  198.     IF GENERATINGCFM THEN
  199.         IMPORT_CFM_FUNCTION RegGetEntryName
  200.     ENDIF
  201.  
  202. ;
  203. ;------------------------------------------------------------------------------------
  204. ;Get Path Name
  205. ;------------------------------------------------------------------------------------
  206. ;
  207. ;
  208. ; These are utility routines to turn an Entry ID back into a name string.
  209. ; Get Entry Path Size
  210. ; Note, path size is returned in bytes for C-String paths
  211. ;
  212. ;
  213. ; extern OSStatus RegGetEntryPathSize(RegTransaction transaction, const RegEntryRef *entryRef, ByteCount *pathSize)
  214. ;
  215.     IF GENERATINGCFM THEN
  216.         IMPORT_CFM_FUNCTION RegGetEntryPathSize
  217.     ENDIF
  218.  
  219. ;  Get Path Name
  220. ;
  221. ; extern OSStatus RegGetEntryPath(RegTransaction transaction, const RegEntryRef *entryRef, char *pathName, ByteCount pathSize)
  222. ;
  223.     IF GENERATINGCFM THEN
  224.         IMPORT_CFM_FUNCTION RegGetEntryPath
  225.     ENDIF
  226.  
  227. ;
  228. ;------------------------------------------------------------------------------------
  229. ; Entry Iteration
  230. ;------------------------------------------------------------------------------------
  231. ;
  232. ;
  233. ; An Entry Iterator maintains three variables that are of interest to clients.
  234. ; First is an "OutermostScope" which defines the outer boundry of the iteration.
  235. ; This is defined by the starting entry and includes that entry plus all of it's
  236. ; embedded entries. Second is a "currentScope" which is the entry the iterator is
  237. ; currently in. And third is a "currentPosition" which is the last entry returned
  238. ; during an iteration.
  239. ; Create Entry Iterator
  240. ; Create the iterator structure. The outermostScope and currentScope of the iterator
  241. ; are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
  242. ; currentScope are set to the root entry.  The currentPosition for the iterator is
  243. ; set to "nil".
  244. ; If propertyName != Null, propertyName, propertyValue, and propertySize are used
  245. ; to filter the entries returned during an iteration.  If propertyName == Null, all
  246. ; entries are returned.
  247. ;
  248. ;
  249. ; extern OSStatus RegCreateEntryIterator(RegTransaction transaction, const RegEntryRef *startEntry, RegEntryIteratorOptions options, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegEntryIterator *iterator)
  250. ;
  251.     IF GENERATINGCFM THEN
  252.         IMPORT_CFM_FUNCTION RegCreateEntryIterator
  253.     ENDIF
  254.  
  255. ;  Dispose Entry Iterator
  256. ;
  257. ; extern OSStatus RegDisposeEntryIterator(RegEntryIterator iterator)
  258. ;
  259.     IF GENERATINGCFM THEN
  260.         IMPORT_CFM_FUNCTION RegDisposeEntryIterator
  261.     ENDIF
  262.  
  263. ;
  264. ; Enter Child Entry
  265. ; Move an Entry Iterator into the scope of a specified child entry.  The
  266. ; currentScope of the iterator is set to the entry specified in "childEntry".  If
  267. ; "childEntry" is nil, the currentScope is set to the entry specified by the
  268. ; currentPosition of the iterator.
  269. ; Note RegEnterEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  270. ; set when the iterator was created. 
  271. ;
  272. ;
  273. ; extern OSStatus RegEnterEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *childEntry)
  274. ;
  275.     IF GENERATINGCFM THEN
  276.         IMPORT_CFM_FUNCTION RegEnterEntry
  277.     ENDIF
  278.  
  279. ;
  280. ; Exit to Parent Entry
  281. ; Move an Entry Iterator out of the current entry back into the scope of it's parent
  282. ; entry. The currentPosition of the iterator is reset to the current entry (the
  283. ; previous currentScope), so the next iteration call will continue where it left off.
  284. ; This position is returned in parameter "currentPosition".
  285. ; Note RegExitEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  286. ; set when the iterator was created. 
  287. ;
  288. ;
  289. ; extern OSStatus RegExitEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *currentPosition)
  290. ;
  291.     IF GENERATINGCFM THEN
  292.         IMPORT_CFM_FUNCTION RegExitEntry
  293.     ENDIF
  294.  
  295. ;
  296. ; Iterate Entries 
  297. ; Iterate and return entries contained within the entry defined by the current
  298. ; scope of the iterator. If kRegIterateEmbeddedEntries option was specified when the
  299. ; iterator was created, all embedded entries will be included in the iteration.  If a
  300. ; property selection (name , value, and size) was specified when the iterator was
  301. ; created, the only entries having a matching property are returned.  Entries are
  302. ; returned one at a time. When OSStatus == nrIterationDone, all entries have been exhausted, and the
  303. ; value of nextEntry will be Nil. If changed == true, one or more changes (entry
  304. ; create or delete) occured since the last interation call.
  305. ;
  306. ;
  307. ; extern OSStatus RegIterateEntries(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *nextEntry, Boolean *changed)
  308. ;
  309.     IF GENERATINGCFM THEN
  310.         IMPORT_CFM_FUNCTION RegIterateEntries
  311.     ENDIF
  312.  
  313. ;
  314. ; Restart Entry Iteration
  315. ; Restart an iteration within the current scope.  The iterator is reset such that
  316. ; iteration of the contents of the currentScope entry can be restarted. The
  317. ; outermostScope and currentScope of the iterator are unchanged. The currentPosition
  318. ; for the iterator is set to "nil".
  319. ;
  320. ;
  321. ; extern OSStatus RegRestartEntryIteration(RegEntryIterator iterator)
  322. ;
  323.     IF GENERATINGCFM THEN
  324.         IMPORT_CFM_FUNCTION RegRestartEntryIteration
  325.     ENDIF
  326.  
  327. ;
  328. ;------------------------------------------------------------------------------------
  329. ; Adding and Deleting Properties
  330. ;------------------------------------------------------------------------------------
  331. ;
  332. ;
  333. ; Create Property
  334. ; A  single instance property is created by default. To create a multiple-instance
  335. ; property set the kRegMultiInstanceProperty option. The next instance of the
  336. ; property will be created and the instance value will be returned in
  337. ; propertyInstance.
  338. ;
  339. ;
  340. ; extern OSStatus RegCreateProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegCreatePropertyOptions options, RegPropertyInstance *propertyInstance)
  341. ;
  342.     IF GENERATINGCFM THEN
  343.         IMPORT_CFM_FUNCTION RegCreateProperty
  344.     ENDIF
  345.  
  346. ;
  347. ; Delete Property
  348. ; To delete a property the desired property instance(s) must be explicitly
  349. ; identified. To delete a single instance property set propertyInstance to
  350. ; kRegNilPropertyInstance.  To delete all instances of a multi-instance property, set
  351. ; propertyInstance to kRegAllPropertyInstances.  Otherwise, propertyInstance must
  352. ; be set to a valid instance value.
  353. ;
  354. ;
  355. ; extern OSStatus RegDeleteProperty(RegTransaction transaction, const RegEntryRef *EntryRef, const char *propertyName, RegPropertyInstance propertyInstance)
  356. ;
  357.     IF GENERATINGCFM THEN
  358.         IMPORT_CFM_FUNCTION RegDeleteProperty
  359.     ENDIF
  360.  
  361. ;
  362. ;------------------------------------------------------------------------------------
  363. ; Get/Set Property Values
  364. ;------------------------------------------------------------------------------------
  365. ;
  366. ;
  367. ; Get/Set the value of the specified property for the specified entry.  To get, get
  368. ; size, and set property values the desired property instance must be explicitly
  369. ; identified.  For single instance properites propertyInstance must  be set to
  370. ; kRegNilPropertyInstance.  Otherwise, propertyInstance must be set to a valid
  371. ; instance value.
  372. ; Get Property size
  373. ;
  374. ;
  375. ; extern OSStatus RegGetPropertySize(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, ByteCount *propertySize)
  376. ;
  377.     IF GENERATINGCFM THEN
  378.         IMPORT_CFM_FUNCTION RegGetPropertySize
  379.     ENDIF
  380.  
  381. ;  Get Property
  382. ;
  383. ; extern OSStatus RegGetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, void *propertyValue, ByteCount *propertySize)
  384. ;
  385.     IF GENERATINGCFM THEN
  386.         IMPORT_CFM_FUNCTION RegGetProperty
  387.     ENDIF
  388.  
  389. ;  Set Property
  390. ;
  391. ; extern OSStatus RegSetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, const void *propertyValue, ByteCount propertySize)
  392. ;
  393.     IF GENERATINGCFM THEN
  394.         IMPORT_CFM_FUNCTION RegSetProperty
  395.     ENDIF
  396.  
  397. ;
  398. ;------------------------------------------------------------------------------------
  399. ; Iterating Properties
  400. ;------------------------------------------------------------------------------------
  401. ;
  402. ;
  403. ; Create Property Iterator
  404. ; Create the property iterator structure. The target entry is defined by entryRef.
  405. ; If a propertyName is specified, only property instances having the specified name
  406. ; are returned. If propertyName == nil, all properties are returned.
  407. ;
  408. ;
  409. ; extern OSStatus RegCreatePropertyIterator(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyIterator *iterator)
  410. ;
  411.     IF GENERATINGCFM THEN
  412.         IMPORT_CFM_FUNCTION RegCreatePropertyIterator
  413.     ENDIF
  414.  
  415. ;  Dispose Property Iterator
  416. ;
  417. ; extern OSStatus RegDisposePropertyIterator(RegPropertyIterator iterator)
  418. ;
  419.     IF GENERATINGCFM THEN
  420.         IMPORT_CFM_FUNCTION RegDisposePropertyIterator
  421.     ENDIF
  422.  
  423. ;
  424. ; Iterate Properites
  425. ; Iterate and return properties for given entry.  If a propertyName was specified
  426. ; when the iterator was created, then only property instances for that name are
  427. ; returned. Otherwise, all properties are returned.  The return value in
  428. ; propertyInstance will be kRegNilPropertyInstance if the property is single
  429. ; instance.  Else it will contain the instance value for the property. If
  430. ; changed == true, one or more changes (property creates or deletes) occured since the
  431. ; last iterate call.  When OSStatus == nrIterationDone, all properties have been exhausted.
  432. ;
  433. ;
  434. ; extern OSStatus RegIterateProperties(RegTransaction transaction, RegPropertyIterator iterator, char *foundProperty, RegPropertyInstance *propertyInstance, Boolean *changed)
  435. ;
  436.     IF GENERATINGCFM THEN
  437.         IMPORT_CFM_FUNCTION RegIterateProperties
  438.     ENDIF
  439.  
  440. ;
  441. ; Restart Property Iteration
  442. ; Used to re-iterate over a list of properties.  The Property Iterator is reset to
  443. ; the beginning of the list of properties for an entry.
  444. ;
  445. ;
  446. ; extern OSStatus RegRestartPropertyIteration(RegPropertyIterator iterator)
  447. ;
  448.     IF GENERATINGCFM THEN
  449.         IMPORT_CFM_FUNCTION RegRestartPropertyIteration
  450.     ENDIF
  451.  
  452. ;
  453. ;------------------------------------------------------------------------------------
  454. ; Transaction-control calls
  455. ;------------------------------------------------------------------------------------
  456. ;
  457. ;
  458. ; Begin Transaction
  459. ; Marks the beginning of a sequence of Name Registry calls that compose a Registry
  460. ; transaction.  An internal data structure for the transaction is created and a
  461. ; reference to the transaction is returned in "tranasaction". This reference must be
  462. ; used with all subsequence Name Registry calls pertaining to the transaction. The
  463. ; transaction reference must be disposed using a RegCommitTransaction or
  464. ; RegAbortTranscation call.    
  465. ;
  466. ;
  467. ; extern OSStatus RegBeginTransaction(RegTransaction *transaction)
  468. ;
  469.     IF GENERATINGCFM THEN
  470.         IMPORT_CFM_FUNCTION RegBeginTransaction
  471.     ENDIF
  472.  
  473. ;
  474. ; Commit Transaction
  475. ; Commits the changes made to the registry for a sepecified transaction. All changes
  476. ; (entry create/delete, property create/delete, and  property value update) made for
  477. ; the transaction are atomically integrated into the Registry.  If result ==
  478. ; nrTransactionAborted, there was a conflict with changes from some other transaction,
  479. ; and this transaction was aborted, i.e., no changes for this transaction were made.
  480. ; In this case the transaction should be repeated.
  481. ; Note that RegCommitTransaction always disposes the transcation reference
  482. ; independant of the outcome of the transaction.  So to repeat a transaaction you
  483. ; must start over with a RegBeginTransaction call.
  484. ;
  485. ;
  486. ; extern OSStatus RegCommitTransaction(RegTransaction transaction)
  487. ;
  488.     IF GENERATINGCFM THEN
  489.         IMPORT_CFM_FUNCTION RegCommitTransaction
  490.     ENDIF
  491.  
  492. ;
  493. ; Abort Transaction
  494. ; Aborts the changes made to the registry for a sepecified transaction. All changes
  495. ; (entry create/delete, property create/delete, and  property value update) made for
  496. ; the transaction are disgarded.  
  497. ; RegAbortTransaction also disposes of the transcation reference.
  498. ;
  499. ;
  500. ; extern OSStatus RegAbortTransaction(RegTransaction transaction)
  501. ;
  502.     IF GENERATINGCFM THEN
  503.         IMPORT_CFM_FUNCTION RegAbortTransaction
  504.     ENDIF
  505.  
  506.     ENDIF
  507.     IF FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED THEN
  508. ;
  509. ;------------------------------------------------------------------------------------
  510. ;    Name Registry Interface for PowerSurge 1.0.2
  511. ;------------------------------------------------------------------------------------
  512. ;
  513. ;
  514. ; * Name Registry - API for device driver name registration
  515. ; *
  516. ; * This interface provides access to the namespace used
  517. ; * by device drivers.  The data structures and entry points
  518. ; * are specialized and simplified for device driver use.
  519. ;
  520. ;
  521. ; //////////////////////////////////////////////////////////////////////////////
  522. ;//
  523. ;// Data Structures
  524. ;//
  525. ;
  526. ;
  527. ; //////////////////////////////////////////////////////////////////////////////
  528. ;// 
  529. ;// Foundation Types
  530. ;//
  531. ;
  532. ;  Value of a property 
  533. ; typedef void *                        RegPropertyValue
  534.  
  535. ;  Length of property value 
  536. ; typedef UInt32                         RegPropertyValueSize
  537.  
  538. ;
  539. ; //////////////////////////////////////////////////////////////////////////////
  540. ;// 
  541. ;// RegEntryID    :    The Global x-Namespace Entry Identifier
  542. ;//
  543. ;
  544. ;  RegEntryID:    The Global Entry ID
  545. RegEntryID                RECORD 0
  546. f                         ds        RegEntryRef
  547. sizeof                     EQU *                    ; size:   $10 (16)
  548.                         ENDR
  549.  
  550.  
  551. ; typedef struct RegEntryID *            RegEntryIDPtr
  552.  
  553. ;
  554. ; //////////////////////////////////////////////////////////////////////////////
  555. ;//
  556. ;// Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  557. ;//
  558. ;//    * Names are a colon-separated list of name components.  Name components
  559. ;//      may not themselves contain colons.  
  560. ;//    * Names are presented as null-terminated ASCII character strings.
  561. ;//    * Names follow similar parsing rules to Apple file system absolute
  562. ;//      and relative paths.  However the '::' parent directory syntax is
  563. ;//      not currently supported.
  564. ;
  565. ;  Max length of Entry Name 
  566.  
  567. kRegCStrMaxEntryNameLength        EQU        47
  568. ;  Entry Names are single byte ASCII 
  569. ; typedef char                             RegCStrEntryName
  570.  
  571. ; typedef char *                        RegCStrEntryNamePtr
  572.  
  573. ;  length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1
  574. RegCStrEntryNameBuf        RECORD 0
  575. elements                 ds.b    48
  576. sizeof                     EQU *                    ; size:   $30 (48)
  577.                         ENDR
  578.  
  579.  
  580. ; typedef char                             RegCStrPathName
  581.  
  582. ; typedef UInt32                         RegPathNameSize
  583.  
  584.  
  585. kRegEntryNameTerminator            EQU        $00                    ; '\0' 
  586. kRegPathNameTerminator            EQU        $00                    ; '\0' 
  587. ;
  588. ; //////////////////////////////////////////////////////////////////////////////
  589. ;//
  590. ;// Property Name and ID Definitions
  591. ;//    (Applies to all Properties Regardless of NameSpace)
  592. ;
  593.  
  594. kRegMaximumPropertyNameLength    EQU        31                    ; Max length of Property Name 
  595. kRegPropertyNameTerminator        EQU        $00                    ; '\0' 
  596. ; typedef char                             RegPropertyName
  597.  
  598. ; typedef char *                        RegPropertyNamePtr
  599.  
  600. ;
  601. ; //////////////////////////////////////////////////////////////////////////////
  602. ;//
  603. ;// Iteration Operations
  604. ;//
  605. ;//    These specify direction when traversing the name relationships
  606. ;
  607. ; typedef UInt32                         RegIterationOp
  608.  
  609. ; typedef RegIterationOp                 RegEntryIterationOp
  610.  
  611.  
  612.                                                             ; Absolute locations
  613. kRegIterRoot                    EQU        $00000002            ; "Upward" Relationships    
  614. kRegIterParents                    EQU        $00000003            ; include all  parent(s) of entry 
  615.                                                             ; "Downward" Relationships
  616. kRegIterChildren                EQU        $00000004            ; include all children 
  617. kRegIterSubTrees                EQU        $00000005            ; include all sub trees of entry 
  618. kRegIterDescendants                EQU        $00000005            ; include all descendants of entry 
  619.                                                             ; "Horizontal" Relationships    
  620. kRegIterSibling                    EQU        $00000006            ; include all siblings 
  621.                                                             ; Keep doing the same thing
  622. kRegIterContinue                EQU        $00000001
  623. ;
  624. ; //////////////////////////////////////////////////////////////////////////////
  625. ;//
  626. ;// Name Entry and Property Modifiers
  627. ;//
  628. ;
  629. ;//
  630. ;// Modifiers describe special characteristics of names
  631. ;// and properties.  Modifiers might be supported for
  632. ;// some names and not others.
  633. ;// 
  634. ;// Device Drivers should not rely on functionality
  635. ;// specified as a modifier.
  636. ;
  637. ; typedef UInt32                         RegModifiers
  638.  
  639. ; typedef RegModifiers                     RegEntryModifiers
  640.  
  641. ; typedef RegModifiers                     RegPropertyModifiers
  642.  
  643.  
  644. kRegNoModifiers                    EQU        $00000000            ; no entry modifiers in place 
  645. kRegUniversalModifierMask        EQU        $0000FFFF            ; mods to all entries 
  646. kRegNameSpaceModifierMask        EQU        $00FF0000            ; mods to all entries within namespace 
  647. kRegModifierMask                EQU        $FF000000            ; mods to just this entry 
  648. ;  Universal Property Modifiers 
  649.  
  650. kRegPropertyValueIsSavedToNVRAM    EQU        $00000020            ; property is non-volatile (saved in NVRAM) 
  651. kRegPropertyValueIsSavedToDisk    EQU        $00000040            ; property is non-volatile (saved on disk) 
  652. ;
  653. ; ///////////////////////
  654. ;//
  655. ;// The Registry API
  656. ;//
  657. ;/////////////////////// 
  658. ;
  659. ;
  660. ; ///////////////////////
  661. ;//
  662. ;// Entry Management
  663. ;//
  664. ;/////////////////////// 
  665. ;
  666. ;
  667. ;-------------------------------
  668. ; * EntryID handling
  669. ;
  670. ;
  671. ; * Initialize an EntryID to a known invalid state
  672. ; *   note: invalid != uninitialized
  673. ;
  674. ;
  675. ; extern OSStatus RegistryEntryIDInit(RegEntryID *id)
  676. ;
  677.     IF GENERATINGCFM THEN
  678.         IMPORT_CFM_FUNCTION RegistryEntryIDInit
  679.     ENDIF
  680.  
  681. ;
  682. ; * Compare EntryID's for equality or if invalid
  683. ; *
  684. ; * If a NULL value is given for either id1 or id2, the other id 
  685. ; * is compared with an invalid ID.  If both are NULL, the id's 
  686. ; * are consided equal (result = true). 
  687. ;
  688. ;
  689. ; extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2)
  690. ;
  691.     IF GENERATINGCFM THEN
  692.         IMPORT_CFM_FUNCTION RegistryEntryIDCompare
  693.     ENDIF
  694.  
  695. ;
  696. ; * Copy an EntryID
  697. ;
  698. ;
  699. ; extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst)
  700. ;
  701.     IF GENERATINGCFM THEN
  702.         IMPORT_CFM_FUNCTION RegistryEntryIDCopy
  703.     ENDIF
  704.  
  705. ;
  706. ; * Free an ID so it can be reused.
  707. ;
  708. ;
  709. ; extern OSStatus RegistryEntryIDDispose(RegEntryID *id)
  710. ;
  711.     IF GENERATINGCFM THEN
  712.         IMPORT_CFM_FUNCTION RegistryEntryIDDispose
  713.     ENDIF
  714.  
  715. ;
  716. ;-------------------------------
  717. ; * Adding and removing entries
  718. ; *
  719. ; * If (parentEntry) is NULL, the name is assumed
  720. ; * to be a rooted path. It is rooted to an anonymous, unnamed root.
  721. ;
  722. ;
  723. ; extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry)
  724. ;
  725.     IF GENERATINGCFM THEN
  726.         IMPORT_CFM_FUNCTION RegistryCStrEntryCreate
  727.     ENDIF
  728.  
  729. ;
  730. ; extern OSStatus RegistryEntryDelete(const RegEntryID *id)
  731. ;
  732.     IF GENERATINGCFM THEN
  733.         IMPORT_CFM_FUNCTION RegistryEntryDelete
  734.     ENDIF
  735.  
  736. ;
  737. ;---------------------------
  738. ; * Traversing the namespace
  739. ; *
  740. ; * To support arbitrary namespace implementations in the future,
  741. ; * I have hidden the form that the place pointer takes.  The previous
  742. ; * interface exposed the place pointer by specifying it as a
  743. ; * RegEntryID.
  744. ; *
  745. ; * I have also removed any notion of returning the entries
  746. ; * in a particular order, because an implementation might
  747. ; * return the names in semi-random order.  Many name service
  748. ; * implementations will store the names in a hashed lookup
  749. ; * table.
  750. ; *
  751. ; * Writing code to traverse some set of names consists of
  752. ; * a call to begin the iteration, the iteration loop, and
  753. ; * a call to end the iteration.  The begin call initializes
  754. ; * the iteration cookie data structure.  The call to end the 
  755. ; * iteration should be called even in the case of error so 
  756. ; * that allocated data structures can be freed.
  757. ; *
  758. ; *    Create(...)
  759. ; *    do {
  760. ; *        Iterate(...);
  761. ; *    } while (!done);
  762. ; *    Dispose(...);
  763. ; *
  764. ; * This is the basic code structure for callers of the iteration
  765. ; * interface.
  766. ;
  767.  
  768.  
  769. ;
  770. ; * create/dispose the iterator structure
  771. ; *   defaults to root with relationship = kRegIterDescendants
  772. ;
  773. ;
  774. ; extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie)
  775. ;
  776.     IF GENERATINGCFM THEN
  777.         IMPORT_CFM_FUNCTION RegistryEntryIterateCreate
  778.     ENDIF
  779.  
  780. ;
  781. ; extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie)
  782. ;
  783.     IF GENERATINGCFM THEN
  784.         IMPORT_CFM_FUNCTION RegistryEntryIterateDispose
  785.     ENDIF
  786.  
  787. ;
  788. ; * set Entry Iterator to specified entry
  789. ;
  790. ;
  791. ; extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID)
  792. ;
  793.     IF GENERATINGCFM THEN
  794.         IMPORT_CFM_FUNCTION RegistryEntryIterateSet
  795.     ENDIF
  796.  
  797. ;
  798. ; * Return each value of the iteration
  799. ; *
  800. ; * return entries related to the current entry
  801. ; * with the specified relationship
  802. ;
  803. ;
  804. ; extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done)
  805. ;
  806.     IF GENERATINGCFM THEN
  807.         IMPORT_CFM_FUNCTION RegistryEntryIterate
  808.     ENDIF
  809.  
  810. ;
  811. ; * return entries with the specified property
  812. ; *
  813. ; * A NULL RegPropertyValue pointer will return an
  814. ; * entry with the property containing any value.
  815. ;
  816. ;
  817. ; extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  818. ;
  819.     IF GENERATINGCFM THEN
  820.         IMPORT_CFM_FUNCTION RegistryEntrySearch
  821.     ENDIF
  822.  
  823. ;
  824. ;--------------------------------
  825. ; * Find a name in the namespace
  826. ; *
  827. ; * This is the fast lookup mechanism.
  828. ; * NOTE:  A reverse lookup mechanism
  829. ; *      has not been provided because
  830. ; *        some name services may not
  831. ; *        provide a fast, general reverse
  832. ; *        lookup.
  833. ;
  834. ;
  835. ; extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry)
  836. ;
  837.     IF GENERATINGCFM THEN
  838.         IMPORT_CFM_FUNCTION RegistryCStrEntryLookup
  839.     ENDIF
  840.  
  841. ;
  842. ;---------------------------------------------
  843. ; * Convert an entry to a rooted name string
  844. ; *
  845. ; * A utility routine to turn an Entry ID
  846. ; * back into a name string.
  847. ;
  848. ;
  849. ; extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize)
  850. ;
  851.     IF GENERATINGCFM THEN
  852.         IMPORT_CFM_FUNCTION RegistryEntryToPathSize
  853.     ENDIF
  854.  
  855. ;
  856. ; extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize)
  857. ;
  858.     IF GENERATINGCFM THEN
  859.         IMPORT_CFM_FUNCTION RegistryCStrEntryToPath
  860.     ENDIF
  861.  
  862. ;
  863. ; * Parse a path name.
  864. ; *
  865. ; * Retrieve the last component of the path, and
  866. ; * return a spec for the parent.
  867. ;
  868. ;
  869. ; extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done)
  870. ;
  871.     IF GENERATINGCFM THEN
  872.         IMPORT_CFM_FUNCTION RegistryCStrEntryToName
  873.     ENDIF
  874.  
  875. ;
  876. ; //////////////////////////////////////////////////////
  877. ;//
  878. ;// Property Management
  879. ;//
  880. ;////////////////////////////////////////////////////// 
  881. ;
  882. ;
  883. ;-------------------------------
  884. ; * Adding and removing properties
  885. ;
  886. ;
  887. ; extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  888. ;
  889.     IF GENERATINGCFM THEN
  890.         IMPORT_CFM_FUNCTION RegistryPropertyCreate
  891.     ENDIF
  892.  
  893. ;
  894. ; extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName)
  895. ;
  896.     IF GENERATINGCFM THEN
  897.         IMPORT_CFM_FUNCTION RegistryPropertyDelete
  898.     ENDIF
  899.  
  900. ;
  901. ;---------------------------
  902. ; * Traversing the Properties of a name
  903. ; *
  904. ;
  905.  
  906.  
  907. ;
  908. ; extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie)
  909. ;
  910.     IF GENERATINGCFM THEN
  911.         IMPORT_CFM_FUNCTION RegistryPropertyIterateCreate
  912.     ENDIF
  913.  
  914. ;
  915. ; extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie)
  916. ;
  917.     IF GENERATINGCFM THEN
  918.         IMPORT_CFM_FUNCTION RegistryPropertyIterateDispose
  919.     ENDIF
  920.  
  921. ;
  922. ; extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done)
  923. ;
  924.     IF GENERATINGCFM THEN
  925.         IMPORT_CFM_FUNCTION RegistryPropertyIterate
  926.     ENDIF
  927.  
  928. ;
  929. ; * Get the value of the specified property for the specified entry.
  930. ; *
  931. ;
  932. ;
  933. ; extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize)
  934. ;
  935.     IF GENERATINGCFM THEN
  936.         IMPORT_CFM_FUNCTION RegistryPropertyGetSize
  937.     ENDIF
  938.  
  939. ;
  940. ; * (*propertySize) is the maximum size of the value returned in the buffer
  941. ; * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  942. ; * value returned.
  943. ;
  944. ;
  945. ; extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize)
  946. ;
  947.     IF GENERATINGCFM THEN
  948.         IMPORT_CFM_FUNCTION RegistryPropertyGet
  949.     ENDIF
  950.  
  951. ;
  952. ; extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize)
  953. ;
  954.     IF GENERATINGCFM THEN
  955.         IMPORT_CFM_FUNCTION RegistryPropertySet
  956.     ENDIF
  957.  
  958. ;
  959. ; //////////////////////////////////////////////////////
  960. ;//
  961. ;// Modibute (err, I mean Modifier) Management
  962. ;//
  963. ;////////////////////////////////////////////////////// 
  964. ;
  965. ;
  966. ; * Modifiers describe special characteristics of names
  967. ; * and properties.  Modifiers might be supported for
  968. ; * some names and not others.
  969. ; * 
  970. ; * Device Drivers should not rely on functionality
  971. ; * specified as a modifier.  These interfaces
  972. ; * are for use in writing Experts.
  973. ;
  974. ;
  975. ; * Get and Set operators for entry modifiers
  976. ;
  977. ;
  978. ; extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers)
  979. ;
  980.     IF GENERATINGCFM THEN
  981.         IMPORT_CFM_FUNCTION RegistryEntryGetMod
  982.     ENDIF
  983.  
  984. ;
  985. ; extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers)
  986. ;
  987.     IF GENERATINGCFM THEN
  988.         IMPORT_CFM_FUNCTION RegistryEntrySetMod
  989.     ENDIF
  990.  
  991. ;
  992. ; * Get and Set operators for property modifiers
  993. ;
  994. ;
  995. ; extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers)
  996. ;
  997.     IF GENERATINGCFM THEN
  998.         IMPORT_CFM_FUNCTION RegistryPropertyGetMod
  999.     ENDIF
  1000.  
  1001. ;
  1002. ; extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers)
  1003. ;
  1004.     IF GENERATINGCFM THEN
  1005.         IMPORT_CFM_FUNCTION RegistryPropertySetMod
  1006.     ENDIF
  1007.  
  1008. ;
  1009. ; * Iterator operator for entry modifier search
  1010. ;
  1011. ;
  1012. ; extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers)
  1013. ;
  1014.     IF GENERATINGCFM THEN
  1015.         IMPORT_CFM_FUNCTION RegistryEntryMod
  1016.     ENDIF
  1017.  
  1018. ;
  1019. ; * Iterator operator for entries with matching 
  1020. ; * property modifiers
  1021. ;
  1022. ;
  1023. ; extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers)
  1024. ;
  1025.     IF GENERATINGCFM THEN
  1026.         IMPORT_CFM_FUNCTION RegistryEntryPropertyMod
  1027.     ENDIF
  1028.  
  1029.     ENDIF
  1030.     ENDIF ; __NAMEREGISTRY__ 
  1031.  
  1032.